/*
 * @(#)AclEntry.java	1.10 01/12/12
 *
 * Sun Microsystems, Inc.版权所有版权所有。太阳专有/保密。使用受许可条款的约束。
 */

package java.security.acl;

import java.util.Enumeration;
import java.security.Principal;

/**
 * 该接口用于表示访问控制列表(ACL)中的一个条目。<p>
 * 
 * 可以将ACL视为具有多个ACL条目对象的数据结构。每个ACL条目对象包含一组与特定主体相关联的权限。
 * (主体代表一个实体，如个人用户或组)。此外，每个ACL条目被指定为正或负。如果为正数，则将权限授予关联主体。
 * 如果为否定，则拒绝权限。每个主体最多可以有一个正ACL表项和一个负ACL表项;即任何主体不允许存在多个正ACL或负ACL表项。
 *
 * 注意:缺省情况下，ACL表项为正。只有当<a href ="#setNegativePermissions">setNegativePermissions</a>方法被调用。
 * 
 * @see Acl
 *
 * @author 	Satish Dharmaraj
 */
public interface AclEntry extends Cloneable {

    /**
     * 指定该ACL项授予或拒绝其权限的主体。如果已经为这个ACL条目设置了主体，则返回false，否则返回true。
     * 
     * @param user the principal to be set for this entry.
     * 
     * @return 如果已设置主体，则为True;如果已为此条目设置主体，则为false。
     */
    public boolean setPrincipal(Principal user);

    /**
     * 返回该ACL项授予或拒绝其权限的主体。如果尚未为此条目设置主体，则返回null。
     * 
     * @return the principal associated with this entry.
     */
    public Principal getPrincipal();

    /**
     * 设置此ACL表项为负ACL表项。也就是说，关联的主体(例如，用户或组)将被拒绝使用条目中指定的权限集。
     * 
     * 注意:缺省情况下，ACL表项为正。只有在<code>setNegativePermissions</code>方法被调用时，条目才会变成负条目。
     */
    public void setNegativePermissions();

    /**
     * 如果这是一个负ACL条目(拒绝关联主体使用条目中的权限集)，则返回true，否则返回false。
     * 
     * @return true if this is a negative ACL entry, false if it's not.
     */
    public boolean isNegative();

    /**
     * 将指定的权限添加到此ACL表项中。注意:一个条目可以有多个权限。
     * 
     * @param permission 要关联的权限这个分录中的主体。
     * 
     * @return 如果添加了该权限，则为True;如果该权限已经是此条目的权限集的一部分，则为false。
     */
    public boolean addPermission(Permission permission);

    /**
     * Removes the specified permission from this ACL entry.
     *  
     * @param permission the permission to be removed from this entry.
     * 
     * @return 如果该权限已被删除，则为True;如果该权限不属于该条目的权限集，则为false。
     */
    public boolean removePermission(Permission permission);

    /**
     * 检查指定的权限是否属于此条目中权限集的一部分。
     * 
     * @param permission the permission to be checked for.
     * 
     * @return 如果权限是此条目中权限集的一部分，则为True，否则为false。
     */
    public boolean checkPermission(Permission permission);

    /**
     * Returns an enumeration of the permissions in this ACL entry.
     * 
     * @return an enumeration of the permissions in this ACL entry.
     */
    public Enumeration permissions();

    /**
     * Returns a string representation of the contents of this ACL entry.
     * 
     * @return a string representation of the contents.
     */
    public String toString();

    /**
     * Clones this ACL entry.
     * 
     * @return a clone of this ACL entry.
     */
    public Object clone();
}


